A Hypertext System for Literate C++ Programming

Programs are written to be executed by computers rather than to be read by humans. This complicates program comprehension, which plays a major role in software maintenance. Literate programming is an approach to improve program understanding by regarding programs as works of literature (see [Knu84]). In this paper we present a tool that supports literate programming with the objectoriented programming language C++. The tool is based on a hypertext system which has been developed to support program comprehension and, thus, software maintenance. An introduction of the basic hypertext system is followed by a presentation of the global structure of the documentation. Afterwards, the user interface of the tool, its use and a sample documentation are given. Some implementation aspects conclude the presentation. In t roduct ion Development programmers hate documentation which, therefore, almost never is either complete or consistent. Maintenance programmers need documentation to understand the software system they are responsible for. But they have to be satisfied with the listing, the only accurate and complete representation of the system. Understanding programs is one of the most time-consuming activities in software maintenance. By improving the availability of complete and up-to-date documentation, we can minimize software costs considerably. When writing programs, we should not try to instruct the computer what to do, but rather we should try to tell humans what we want the computer to do. This is the main idea of literate programming (see [Knu84], [Ben86], [Lin89], [Lind89], [Wyk90]) which leads to significantly better documentation. But as humans and computers do not speak the same language, there is a need for systems that support the idea of literate programming. The WEB System [Knu84] — the original literate programming system — offers a combination of a document formatting language for the documentation text and a programming language for the source code (Pascal). With WEB the source code and its documentation can be written in parallel and in a single document. The system then produces both a clearly readable program description, intended for human readers, and pure source code, intended for compilation and execution on the computer. This work was supported by Siemens AG, Munich, Germany. Several tools for literate programming have been developed so far. They support different languages like C ([Tun89], [Thi86]), Fortran [Ave90], and Smalltalk [Ree89]. Even a generator for WEB-systems is available [Ram89], which can be used to construct instances of WEB from a language description. But these systems, like the original one, are clumsy to use and assume that a program and its documentation are written straightforward. We have based our tool on hypertext technology [Con87] to ease the navigation through a software system, both the source code and the documentation. The tool not only supports documenting systems from scratch but also offers the opportunity to document already existing systems. The Documentation Problem Programmers always have an abstract model in their mind of what they are coding. It is important to write down these thoughts in order to make understanding easier. Writing down these thoughts is hardly ever done, for one reason because there is no place to write it. If you write it in a separate file, you do not have any connection between the source code and the corresponding documentation file. But this connection is essential to guarantee consistent documentation. Besides, you can hardly refer to specific parts of the code. The only way is to copy it, but this brings an unresolvable update problem. Another possiblity is to write the documentation straight into the source code (with comments). But this again has its disadvantages: • The source code becomes illegible because of the numerous comments. • Programmers familiar with the code do not want to be annoyed by this bulky information. • The code needed to solve a problem usually is spread over several places in the source code. (This is especially true in object-oriented systems.) Literate programming tools attempt to solve these problems. However, most existing tools support the documentation of new software. They are not very well suited to support the documentation of already existing software. This would require the modification and restructuring of the existing source code. The literate programming tool we present in this paper supports both the documentation of new and already existing software systems written in the object-oriented language C++. Furthermore, it offers hypertext features to comfortably navigate through the system, both the source code and the documentation text. The Hypertext System Our documentation tool is based on a hypertext system that was developed to support software maintenance [Sam90]. We briefly describe this maintenance tool because it is fundamental to the documentation tool. The hypertext editor eases the process of navigating through the files and classes of a C++ software system and helps the user to get information in a fast and easy way. To accomplish this, the files of a C++ program are divided into little pieces of information, i.e., class definitions, method implementations and global declarations. (By global declaration we mean anything that does not belong to a class definition or to a method implementation, like preprocessor statements or global type declarations.) These little chunks of information are managed together with their interrelations. The following relations are used: • A class is contained in a file. • A class inherits from another class. • A method is contained in a file. • A method belongs to a specific class. • A method is overridden in a subclass. • A file is included by other files. Still other relations exist based on identifiers used in a software system: • An identifier is defined in a class or method, or is global to a file. • The use of an identifier is related to a specific definition of this identifier and to other uses of the same identifier. • A comment possibly contains a short description of an identifier, e.g., the description of a class, a method, or an instance variable. Our maintenance tool offers the possibility to easily browse through the system by means of the above relations. Additionally, useful information is displayed to protect the user from getting lost in the complex information web. In order to enhance the readability of the source code, the user can define global styles for different syntactic constructs, e.g., comments, keywords. Additionally, it is possible to highlight single identifiers or identifiers defined in a certain scope. This helps the user to easily answer questions like Which global variables does this method use, and where are they used? The Documentation System The maintenance tool has been enhanced with documentation features to a literate programming environment. The system enables its users to write documentation during the design and coding process and offers easy access to written documentation during the maintenance process. In the following we first describe the general structure of the documentation built with the presented tool. Then we present the user interface and provide sample documentation. General Structure of the Documentation We define our documentation structure to consist of a set of documentation chapters. These chapters are organized very similiar to classes; i.e. they are spread over several files and a hierarchical structure exists among them. A chapter itself consists of a title, documentation text (that is pure ASCII text) and program text (actually a link to the source code). There are two possiblities to use program text in the documentation: 1) single identifiers 2) any text part, i.e. any number of lines of code in succession within a class definition, a method implementation and anything else in a file Single identifiers can be used right within the documentation text, e.g.: ... With these constants we add two entries in the menu identMenu in the method CreateMenuBar of the class HyperTextDocument. ... Source code identifiers are shown boldfaced. The user can choose any font or style for these identifiers. One or more code lines are clearly separated from the documentation text, for example: ... These menu items to copy or paste an identifier are enabled only when the source code has been parsed (i.e. ,alreadyParsed is set to TRUE) and when the current mark (cm) or the last mark copied is an identifier. The method CopiesIdent provides this information. if (cm && cm->CopiesIdent()) identMenu->EnableItem(cIdentCopy); if (GetClipMark() && GetClipMark()->CopiesIdent()) identMenu->EnableItem(cIdentPaste); Finally, whenever one of these menu items (copy or paste of identifiers) is selected by the user, the method DoMenuCommand is executed. ... Unlike the WEB system and other literate programming tools, the source code is not really intermixed with the documentation text. This means that the source files do not contain documentation and the documentation files do not contain source code. There are only links between them and the tool merges the source code into the documentation for browsing. User Interface The user interface concept is based on modern application frameworks and the supported concepts thereof (see [Shn86], [Wei89]). It provides a menu bar, two selection lists, an information box, and an editor window (see Fig. 1).